Scroll to navigation

GLOB(3) Podręcznik programisty Linuksa GLOB(3)

NAZWA

glob, globfree - znalezienie ścieżek odpowiadających wzorcowi, zwolnienie pamięć z glob()

SKŁADNIA

#include <glob.h>

int glob(const char *pattern, int flags,
         int errfunc(const char *epath, int eerrno),
         glob_t *pglob);
void globfree(glob_t *pglob);

OPIS

Funkcja glob() przeszukuje wszystkie ścieżki odpowiadające wzorcowi pattern, stosując przy tym reguły takie, jakich użyłaby powłoka (zobacz glob(7)). Nie jest dokonywane rozwinięcie tyldy ani podstawienie parametrów. Jeśli są one potrzebne, to należy użyć wordexp(3).

Funkcja globfree() zwalnia obszar pamięci zaalokowany dynamicznie przez wcześniejsze wywołanie funkcji glob().

W wyniku wywołania glob() tworzona jest struktura, na którą wskazuje pglob, będący typu glob_t zadeklarowanego w <glob.h> i zawierającego następujące elementy zdefiniowane przez POSIX.2 (mogą też występować dodatkowe, ale jako rozszerzenie):


typedef struct {

size_t gl_pathc; /* Liczba odpowiadających dotąd ścieżek */
char **gl_pathv; /* Lista odpowiadających ścieżek. */
size_t gl_offs; /* Sloty do rezerwowania w `gl_pathv'. */
} glob_t;

Wyniki są zachowywane w dynamicznie przydzielanym obszarze pamięci.

Parametr flags tworzy bitowe OR zera lub więcej następujących symboli stałych modyfikujących zachowanie glob():

oznacza, że należy powrócić po błędzie odczytu (np. gdy katalog nie ma praw odczytu),
oznacza dodawanie ukośnika do każdej ścieżki, która odpowiada katalogowi,
oznacza, że zwracane ścieżki nie mają być sortowane (domyślnie są),
oznacza, że sloty pglob->gl_offs będą rezerwowane na początku listy napisów w pglob->pathv,
oznacza, że jeśli żaden wzorzec nie odpowiada, zwracany jest wzorzec oryginalny,
oznacza, że należy doklejać wyniki do wyników poprzedniego wywołania. Nie należy ustawiać tej flagi przy pierwszym wywołaniu glob().
oznacza, że metaznaki nie mogą być cytowane odwrotnymi ukośnikami,

Parametr flags może również zawierać następujące znaczniki, będące rozszerzeniami GNU nie definiowanymi przez POSIX.2:

oznacza, że początkowa kropka może być dopasowana metaznakiem,

GLOB_ALTDIRFUNC oznacza, że przy dostępie do systemy plików zamiast zwykłych funkcji bibliotecznych używane są funkcje alternatywne pglob->gl_closedir, pglob->gl_readdir, pglob->gl_opendir, pglob->gl_lstati pglob->gl_stat,

oznacza, że rozwijane są wyrażenia nawiasowe {a,b} w stylu csh(1),
oznacza, że wzorzec jest zwracany, gdy nie zawiera metaznaków,
oznacza, że przeprowadzane rozwinięcie tyldy, a
oznacza, że dopasowywane są wyłącznie katalogi.

Jeśli errfunc nie jest równe NULL, to w wypadku błędu będzie ono wywołane z argumentami epath, czyli wskaźnikiem do ścieżki, na której coś się nie powiodło i z eerrno, przechowującym wartość errno, zwróconą przez wywołanie do opendir(), readdir() lub stat(). Jeśli errfunc zwraca wartość niezerową lub jeśli ustawiony jest znacznik GLOB_ERR, glob() zakończy działanie po wywołaniu funkcji errfunc.

Po pomyślnym zakończeniu, pglob->gl_pathc zawiera liczbę pasujących ścieżek, a pglob->gl_pathv wskaźnik do listy trafionych ścieżek. Pierwszy wskaźnik za ostatnią ścieżką ma wartość NULL.

Możliwe jest wywoływanie glob() wielokrotnie. W takim wypadku, należy w następnych wywołaniach ustawić w flags znacznik GLOB_APPEND.

Jako rozszerzenie GNU, pglob->gl_flags jest ustawiane jako or podanych znaczników i GLOB_MAGCHAR, gdy występują metaznaki.

WARTOŚĆ ZWRACANA

Po pomyślnym zakończeniu glob() zwraca zero. Inne możliwe wartości to:

przy braku pamięci,
przy błędzie odczytu i
gdy niczego nie dopasowano.

PRZYKŁADY

Jednym z przykładów użycia jest następujący kod, emulujący wpisanie ls -l *.c ../*.c w powłoce.


glob_t globbuf; globbuf.gl_offs = 2; glob("*.c", GLOB_DOOFFS, NULL, &globbuf); glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf); globbuf.gl_pathv[0] = "ls"; globbuf.gl_pathv[1] = "-l"; execvp("ls", &globbuf.gl_pathv[0]);

ZGODNE Z

POSIX.2

BŁĘDY

Funkcja glob() może zawieść z powodu błędu wywołanych przez nią funkcji, takich jak malloc() czy opendir(). Wywołania te zapiszą kod błędu w errno.

UWAGI

Elementy gl_pathc i gl_offs struktury są w glibc 2.1 zadeklarowane jako size_t, jak powinno być zgodnie z POSIX.2, ale są zadeklarowane jako int w libc4, libc5 i glibc 2.0.

ZOBACZ TAKŻE

ls(1), sh(1), stat(2), exec(3), malloc(3), opendir(3), readdir(3), wordexp(3), glob(7)

1999-09-12 GNU